home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 42 / Mac Magazin and MacEasy Magazine CD - Issue 42.iso / Software / MACup Bestof / Rechner / Menu Events 1.3.1 / Menu Events Help (text) < prev    next >
Text File  |  1998-01-07  |  44KB  |  986 lines
  1.  
  2. Menu Events 1.3.1
  3.  
  4. December 13, 1997
  5.  
  6.  
  7.  
  8. Disclaimer and Copyright Notice
  9.  
  10.  
  11. Menu Events is a free utility which lets you control another application’s
  12. menu commands by sending it an Apple event.  The author, Ross Brown,
  13. makes no warranty, either express or implied, with respect to this
  14. software, its performance, merchantability, or suitability for any
  15. particular purpose.  People using the Menu Events utility do so at their
  16. own risk.  The author disclaims all liability for loss of data, mechanical
  17. damage, or other losses suffered while using the Menu Events utility.
  18.  
  19. Menu Events is an AWOL Software Production, Copyright © 1994-7 Ross
  20. Brown.  All rights reserved.  Permission is granted to make and distribute
  21. copies of this software, provided this disclaimer and copyright notice are
  22. preserved on all copies.  The software may not, however, be sold or
  23. distributed for profit, or included with other software which is sold or
  24. distributed for profit, without the permission of the author.
  25.  
  26. There are no site license fees for the use of Menu Events within an
  27. organization.  The author encourages you to make and distribute as many
  28. copies of the system extension as you wish, for whomever you wish, as
  29. long as it is not for profit.  Menu Events is part of a set of cooperating
  30. programs, AWOL Utilities.  The tutorial help you are reading is designed
  31. for handling by the help server application Help on Wheels, which is also
  32. part of AWOL Utilities.
  33.  
  34.  
  35.  
  36. Distribution Policy
  37.  
  38.  
  39. New versions of individual AWOL Utilities programs, including Menu
  40. Events, are available by anonymous FTP from popular archive sites
  41. including <ftp://sumex-aim.stanford.edu/info-mac/> and its various
  42. mirror sites, such as <ftp://mirrors.aol.com/pub/info-mac/>.
  43.  
  44. For the latest information about AWOL software, including AWOL Utilities,
  45. please visit the AWOL Web page at <http://www.magma.ca/~awolsp/>.
  46.  
  47. Support for AWOL Utilities is through Internet mail at
  48. <mailto:ab026@freenet.carleton.ca>.  The software is not available by
  49. FTP from this site.  The address for paper correspondence is AWOL
  50. Software Productions, PO Box 24207, Hazeldean RPO, Kanata, Ontario,
  51. Canada K2M 2C3.
  52.  
  53. Macintosh users who do not have access to electronic sources of free and
  54. shareware software may obtain a copy of AWOL Utilities by sending a
  55. self-addressed stamped envelope and an 800K (or larger) formatted
  56. diskette to the author at the above address.  U.S. users are reminded that
  57. postage from Canada in 1997 is C$0.52 up to 30 grams (1 oz.), C$0.77 up
  58. to 50 grams (1 3/4 oz.), and C$1.17 up to 100 grams (3 1/2 oz.).
  59. US$0.50, US$0.75, and US$1.00 in coin is acceptable in place of stamps
  60. for the respective weights.  People outside the U.S. and Canada may send
  61. an international postal reply coupon instead of Canadian stamps (available
  62. from any post office).  Please use sturdy envelopes, preferably cardboard
  63. disk mailers.  (Mailers over 5 mm (1/5") thick require C$1.17 postage to
  64. the U.S.)
  65. Please do not send return envelopes with non-Canadian
  66. stamps, as Canada Post will not accept them.
  67.  
  68.  
  69.  
  70. About AWOL Software Productions
  71.  
  72.  
  73. AWOL Software Productions specializes in custom development of
  74. software for the Mac OS.  Since its inception in 1990, AWOL has
  75. developed a number of programs which enhance the Mac OS user
  76. experience, working in nearly every part of the Macintosh Toolbox.  If
  77. you have a short-term programming task or product idea but lack the
  78. staff to do the expert design, coding, and documentation, we invite your
  79. inquiry.
  80.  
  81. Virtual Desktop is AWOL’s best-known effort, serving the desktop
  82. expansion needs of thousands of Mac users around the world.  Later in
  83. 1997, AWOL will release a new commercial version 2.0 to replace the
  84. freeware version contained in the AWOL Utilities package.  Please contact
  85. us at <mailto:ab026@freenet.carleton.ca> for feature and ordering
  86. information.
  87.  
  88. Users who want more out of the Mac’s speech capabilities should check
  89. out MacYack Pro, a jointly developed package of speech tools marketed by
  90. Scantron Quality Computers (<http://www.lowtek.com/macyack/>;
  91. <mailto:qualitycomp@aol.com>; 20200 Nine Mile Rd., St. Clair Shores, MI
  92. 48080).
  93.  
  94.  
  95.  
  96. Purpose
  97.  
  98.  
  99. The big trend these days in Macintosh software is toward more
  100. integration between applications.  Increasingly, developers achieve this
  101. integration by using the Apple event interfaces of other applications, and
  102. by defining their own suites of Apple events for other applications to use.
  103.  
  104. Because there are far more clients than servers in the world of Apple
  105. events, there is a large number of “high-level-event-aware” applications
  106. which support program linking, using Apple events to control other
  107. applications (or just to be modern), but not offering any interface of their
  108. own.  Apart from the Required suite mandated by Finder, the functionality
  109. of these applications is beyond the reach of scripting utilities and other
  110. programs that send Apple events.  Menu Events is a utility which opens up
  111. this demi-monde of dabblers and dilettantes to the glories of Apple event
  112. controllability.  Applications which are by their nature only
  113. high-level-event-aware become scriptable and recordable Apple event
  114. servers.
  115.  
  116. If you regard an application’s collective user interface in terms of a set
  117. of available functions, then take subsets according to how the user can
  118. access these functions (Command-key combination, button click, menus,
  119. and so on), you will usually find that the subset for menus is largest.  This
  120. is because menus are intended as a baseline for the user interface;
  121. however else you can do something, you should be able to do it with menus
  122. as well.  Often a function is not available in a certain mode, but a menu
  123. selection will shift the application into that mode, then another will access
  124. the function.  This conformity is an asset of the Macintosh operating
  125. system which can be exploited to offer a fairly general means of
  126. controlling other applications.
  127.  
  128.  
  129.  
  130. Who Can Use Menu Events?
  131.  
  132.  
  133. You do not need AppleScript, or any other optional software package, for
  134. Menu Events to work.  It only requires System 7.
  135.  
  136. However, it has no user interface of its own.  It only enables programs to
  137. do something they would not otherwise be able to do, namely, invoke
  138. another application’s menu commands.
  139.  
  140. Any program you write, or any application which lets you compose and
  141. send Apple events (such as a general scripting utility, or Maybe, part of
  142. AWOL Utilities), can send a Menu event to any suitably modern application
  143. and hope for a response.  Whether or not a particular application
  144. cooperates depends on how it was programmed, but any application
  145. programmed according to the published instructions of Apple Computer
  146. will cooperate, with a bit of coaxing.
  147. See the section entitled “Limitations” for more information.
  148.  
  149. Menu events can be received from any machine on the AppleTalk network,
  150. subject to the usual Users & Groups program linking permission scheme.
  151. This allows you to use Menu events to control applications from a remote
  152. location.
  153.  
  154. If you have AppleScript, you should place the “Menu Events Scripting
  155. Addition” file in your “Scripting Additions” folder.  This will allow you
  156. to use Menu events in your scripts.  (Unlike most scripting additions, this
  157. one only describes event terminology, and does not implement the event
  158. handlers themselves, so it is useless without the Menu Events extension.)
  159. “Menu Events Sample Script” shows the sort of thing you can do with the
  160. scripting addition file installed.  Before writing a script to control a
  161. target application, you should try recording its menu actions using your
  162. script editor.  If the target application supports program linking, and the
  163. Caps Lock key is down, these actions will be recorded as Menu Events
  164. script commands.
  165.  
  166.  
  167.  
  168. What Does Menu Events Do?
  169.  
  170.  
  171. Menu Events is a system extension.  Once you have placed it in your
  172. Extensions folder and restarted your Macintosh, it adds a small suite of
  173. Apple events (“Menu events”) to the set supported by every
  174. high-level-event-aware application.  Also, if the Caps Lock key is down,
  175. it alters menu selection logic so that the selection is recorded as a Menu
  176. event.  This capability allows a script editor to record menu actions as
  177. script commands.
  178.  
  179. Many people are justly wary of control panels and system extensions,
  180. because of the conflicts they often cause with System software and with
  181. each other.  These conflicts usually result from competitive trap patching.
  182.  
  183. Menu Events installs a GetNextEvent filter and patches the MenuSelect
  184. trap at system startup to enable the Apple event recording capability, and
  185. installs an Apple event handler in the system dispatch table.  The Apple
  186. event handler cannot conflict with any other, because it is bound
  187. specifically to the Menu event class.  Menu Events does patch some traps
  188. “on the fly” to simulate menu selection, but the patches remove
  189. themselves immediately.
  190.  
  191. There are three events defined in the suite, and they work as follows.
  192. See the section entitled “Menu Events Suite” for more information on the
  193. Menu Events suite.
  194.  
  195.  
  196. Query Menu List Event
  197.  
  198. This event, with no parameters, queries the menu list of the target
  199. application.  If the application is high-level-event-aware, not
  200. background-only, and has a menu bar, it will return a list of records, each
  201. containing a menu ID (integer), a title (string), an enable/disable
  202. (Boolean), and a menu definition procedure resource ID (integer)
  203. parameter.  If you do not know the IDs or titles of the target application’s
  204. menus, this is one way to find out.  (Another way is to press the Caps
  205. Lock key and record menu actions using a script editor; yet another is to
  206. use the Menu Grabber application, also part of AWOL Utilities.)  Be aware
  207. that menu IDs do not have to agree with 'MENU' resource IDs, though they
  208. often do.
  209. See the section entitled “Suggestions for Use” for more information on
  210. Menu Grabber.
  211.  
  212. System menus (Keyboard, Help, Application), hierarchical menus, and
  213. pop-up menus do not appear in this list, but the Apple menu does.
  214.  
  215. NOTE:  The standard menu definition procedure ('MDEF') resource ID is 0.
  216. A value of -1 indicates that the menu definition procedure is not a
  217. resource.  Non-standard menu definition procedures may have abnormal
  218. ways of counting, disabling, and displaying menu items, so be careful with
  219. them.
  220.  
  221.  
  222. Query Menu Event
  223.  
  224. This event, given a menu ID (integer) and/or menu title (string)
  225. parameter, queries the items of a certain target application menu.  If the
  226. application has a menu with that ID and/or title, be it a regular, system,
  227. hierarchical, or pop-up menu, it will return a list of records, one per
  228. menu item, each containing a menu item ID (integer), an item text
  229. (string), an enable/disable (Boolean), a mark character (integer), an icon
  230. ID (integer), a style value (integer), and a Command character (integer)
  231. parameter.  The items are numbered starting from 1 at the top end of the
  232. menu.  Separators appear as disabled items with an item text of “-”.
  233.  
  234. This event simulates a simple click in the application’s menu bar, to force
  235. it to bring its menus up to date.
  236.  
  237. You may optionally include Boolean parameters to indicate which modifier
  238. keys (Shift, Control, Option, Command) are pressed at the time of the
  239. simulated menu bar click, in case this makes a difference in the content of
  240. the menu.
  241.  
  242. This event does work for menus which use a non-standard menu definition
  243. procedure ('MDEF'), but the results may or may not reflect what you see
  244. when you pull down the menu, depending on how the procedure was
  245. programmed.
  246.  
  247. This event brings the target application to the front before forcing the
  248. menu bar click upon it.  If the sender was on the same machine, and was
  249. previously in front, it returns to the front after the menu query is
  250. complete.
  251. See the section entitled “How Does Menu Events Work?” for more
  252. information about the method by which Menu Events activates the target
  253. application.
  254.  
  255.  
  256. Select Menu Item Event
  257.  
  258. This event, given a menu ID (integer) and/or menu title (string)
  259. parameter and a menu item ID (integer) and/or menu item text (string)
  260. parameter, asks the application to act as though the user pulled down that
  261. menu and selected that item.  This does not work for the Keyboard and
  262. Application menus, which are not under the control of the application, nor
  263. for the upper (System-defined) part of the Help menu, but it works for
  264. any regular, application-defined, enabled menu item.
  265.  
  266. If you use the menu item text parameter to specify the menu item to
  267. select, be sure to match any special characters in the text, especially the
  268. ellipsis ('…') character which often appears at the end of the string,
  269. which is not the same as three period characters, despite its appearance.
  270.  
  271. You may optionally include Boolean parameters to indicate which modifier
  272. keys (Shift, Control, Option, Command) are pressed at the time of the
  273. simulated menu item selection, in case this makes a difference in the
  274. effect of the selection.
  275.  
  276. This event does work for menus which use a non-standard menu definition
  277. procedure ('MDEF'), but the results may or may not reflect what happens
  278. when you select from the menu, depending on how the procedure was
  279. programmed.
  280.  
  281. This event brings the target application to the front before forcing the
  282. menu selection upon it.  If the sender was on the same machine, and was
  283. previously in front, it returns to the front after the menu action is
  284. complete.
  285. See the section entitled “How Does Menu Events Work?” for more
  286. information about the method by which Menu Events activates the target
  287. application.
  288.  
  289.  
  290.  
  291. How Does Menu Events Work?
  292.  
  293.  
  294. When you send a Query Menu List event, the ideal application dispatches
  295. the resulting high-level event as an Apple event without looking at it.  The
  296. event handler provided by Menu Events forms a reply to the query on the
  297. basis of the application’s menu list structure.  Through all of this, the
  298. application stays in the background or in the foreground, wherever it was
  299. before.
  300.  
  301. When you send a Query Menu or Select Menu Item event, the same things
  302. happen, but the event handling is more complex.
  303.  
  304. First, it verifies that the given menu is valid.  If not, it returns
  305. noSuchMenuErr.
  306.  
  307. Second, it asks for the application to be brought to the front for user
  308. interaction, because it could be dangerous to feed the target application a
  309. menu bar click while it is in the background, something that never happens
  310. in normal operation.  If it is refused, it returns errAENoUserInteraction.
  311.  
  312. Third, it patches some traps so that it can gain control of menu bar clicks.
  313. If it finds that the patches are already in place, meaning that an earlier
  314. Menu event is still pending, it returns menuEventPendingErr.
  315.  
  316. Fourth, if everything is OK, it posts an event to simulate a mouse click in
  317. the menu bar, with modifier keys if specified.  The patched traps tell the
  318. application that no menu item was selected.  The patches then remove
  319. themselves.  This step is solely to ensure that the application brings its
  320. menus up to date.
  321.  
  322. Fifth (in the case of a Select Menu Item event), it verifies that the given
  323. menu item is valid and enabled.  If not, it returns noSuchMenuErr,
  324. noSuchMenuItemErr, or menuItemDisabledErr.  If the menu has a
  325. non-standard menu definition procedure, its way of counting or disabling
  326. items may differ from the norm.  Menu Events assumes that the count and
  327. enable/disable flags are set in the normal fashion.
  328.  
  329. Sixth (in the case of a Select Menu Item event), it posts an event to
  330. simulate another mouse click in the menu bar, with modifier keys if
  331. specified.  The patched traps tell the application that the given item was
  332. selected.  The patches then remove themselves.  From there, it is exactly
  333. as though the user had actually made the selection.
  334.  
  335. NOTE:  When replying to any of the three event types, Menu Events
  336. includes a null “tattoo” parameter to prove that it handled the event,
  337. rather than some handler supplied by the application.  Many Microsoft
  338. applications, for example, bind their own handler over all Apple event
  339. classes, preventing Menu Events from working.  (The handler wouldn’t be
  340. a problem if it returned errAEEventNotHandled when faced with an
  341. unknown Apple event, as it should.)
  342.  
  343.  
  344. User Interaction Policy
  345.  
  346. The Apple Event Manager implements a complicated but sensible model for
  347. joint sender/receiver control over user interaction.  Menu Events doesn’t
  348. know which menu selections will really require user interaction, but even
  349. if it did, it would still have to request user interaction just to bring the
  350. target application to the front, where an application always expects to be
  351. when it sees a mouse-down event.
  352.  
  353. The sending program must set the kAECanInteract or kAEAlwaysInteract
  354. flag in the sendMode parameter to AESend, in order to achieve user
  355. interaction.  It should also set the kAECanSwitchLayer flag, allowing the
  356. target application to come to the front without having to post a
  357. notification request.  If the target application is in the background, and
  358. receives a Menu event with this flag not set, it may go into a notification
  359. wait state, disrupting its usual background event processing behavior.
  360.  
  361. If both the sending program and target application are in the background,
  362. the kAECanSwitchLayer flag has no effect, and the notification request is
  363. posted anyway.  Since your sending program is indirectly instigating a
  364. user interaction, it should call AEInteractWithUser before sending the
  365. Menu event, if there is any chance that it will be in the background at the
  366. time.  Another approach would be to call SetFrontProcess to activate the
  367. target application before sending it a Menu event.
  368.  
  369. If the target application is in that rare user interaction state,
  370. kAEInteractWithSelf, where it disallows interaction requested by any
  371. other process, the Menu event handler will respect that state, and refuse
  372. the event.
  373.  
  374. If the sending and receiving applications are on different machines, the
  375. usual program linking checks apply, namely, Sharing Setup (on/off),
  376. Users & Groups (permission to user), and Finder’s Sharing (permission to
  377. application).
  378.  
  379. If the Menu Events extension is locked, using Finder’s Get Info dialog, then
  380. only target applications which explicitly allow interaction with all
  381. processes can be controlled by remote senders.  If it is not locked, and if
  382. it sees that the user interaction state is kAEInteractWithLocal, which is
  383. the default value, it will momentarily change it to kAEInteractWithAll, so
  384. that events sent from a remote machine are not rejected.  This trick is
  385. necessary for Menu Events to be useful with most target applications,
  386. because most will assume the default interaction state, not expecting any
  387. remote sender to require user interaction.  The icon displayed by Menu
  388. Events at startup shows whether or not the lock is in effect.
  389.  
  390. IMPORTANT NOTE:  Users of machines where Menu Events is installed
  391. should be careful about which users and applications are enabled for
  392. remote program linking.  In particular, guest users should not be allowed
  393. to do program linking unless Menu Events is locked.
  394.  
  395.  
  396. Apple Event Recording Capability
  397.  
  398. When you are using a high-level-event-aware application on a machine
  399. where Menu Events is installed, menu item selection behavior is modified
  400. if the Caps Lock key is down at the time you release the mouse button.
  401. Menu Events will create a Select Menu Item Apple event to represent the
  402. selection (including parameters for any modifier keys which were
  403. pressed), so that a script editor can record the event as a script
  404. command.  A gentle “twang” sound confirms that this has happened.
  405. Whether or not it succeeds in recording the event, the menu selection will
  406. be processed in the usual way.
  407.  
  408. If the application is scriptable in its own right, a script editor may record
  409. two commands when you select an item from its menus.  To prevent this
  410. duplication, you can use the item’s Command-key equivalent (if any), or
  411. release the Caps Lock key, to suppress the recording capability.
  412.  
  413. If an application seems to be misinterpreting or not receiving menu
  414. selections, try again with the Caps Lock key up.  The command will not be
  415. recorded, but should work as usual.
  416.  
  417. NOTE:  While receiving a Select Menu Item event does simulate a menu
  418. selection, it does not cause a Select Menu Item script command to be
  419. recorded.
  420.  
  421.  
  422.  
  423. Suggestions for Use
  424.  
  425.  
  426. Menu Events is distributed as part of a free set of cooperating programs,
  427. AWOL Utilities.  This section explains how Menu Events can work in
  428. conjunction with the other programs.
  429.  
  430.  
  431. Help on Wheels
  432.  
  433. Help on Wheels is an efficient and full-featured help server which displays
  434. help files on behalf of client applications.  The help file you are reading is
  435. distributed alongside the Menu Events extension file as a separate Help on
  436. Wheels document.
  437.  
  438. Because Menu Events is not an application, its help support is limited.  To
  439. read this help, press the Help or Command-? key while the machine is
  440. starting up, and release the key once you see the Menu Events icon with a
  441. help balloon on it.  The help server will open to display the help file after
  442. startup is complete.
  443.  
  444.  
  445. Maybe
  446.  
  447. Maybe, the Finder alias enhancer, has an option allowing you to script a
  448. single Apple event and choose its target.  This Apple event will be sent
  449. just before the alias target is opened or printed.  In this way, you can
  450. achieve the effect of sending a simple Menu event by opening the
  451. converted alias.
  452.  
  453. Maybe does not require AppleScript or any other scripting system to send
  454. a Menu event.  Many programs, including all kinds of scripting utilities,
  455. offer a similar opportunity to send Menu events to any target application
  456. you choose.
  457.  
  458.  
  459. Menu Grabber
  460.  
  461. AWOL Utilities also contains an application, Menu Grabber, which uses
  462. Menu events to swap any target application’s menu bar over its own.
  463. This allows you to command most of the application’s functions from a
  464. remote location, although you will not see anything but the menus.  For
  465. most target applications, Menu Grabber will only be able to select menu
  466. items from a remote machine if the target’s copy of Menu Events was
  467. unlocked at startup.
  468. See the section entitled “User Interaction Policy” for more information
  469. about the effect of locking the Menu Events extension.
  470.  
  471. When Menu Grabber grabs a menu, it adds a disabled item to show the
  472. menu ID.  This may help you if you are writing a program or script to send
  473. a Menu event to the application.
  474.  
  475.  
  476.  
  477. Menu Events Suite
  478.  
  479.  
  480. The following is a formal description of the Menu Events suite, in the form
  481. used in the Apple Event Registry.
  482.  
  483. NOTE:  The C header file “Menu Events.h” contains the constant
  484. definitions which appear here.  The “Menu Events Scripting Addition” file
  485. contains an 'aete' resource which records the following dictionary
  486. information, for the benefit of scripting packages such as AppleScript.
  487. This package also includes a sample script, “Menu Events Sample
  488. Script,” which demonstrates the usage of the following events and
  489. parameters.
  490.  
  491.  
  492. Apple events defined in the Menu Events suite
  493.  
  494. Name              Requested action
  495.  
  496. Query Menu List   List all application-defined menus
  497. Query Menu        List all items in a menu
  498. Select Menu Item  Perform a menu command
  499.  
  500.  
  501. Query Menu List - list all application-defined menus
  502.  
  503. A Query Menu List Apple event asks the application to return a list of
  504. records containing information about all menus defined by the application
  505. in its menu bar.  This information includes the Apple menu, but not the
  506. Help, Keyboard, or Application menus.
  507.  
  508. Event Class       kMEEventClass
  509.  
  510. Event ID          kAEMEQueryMenuList
  511.  
  512. Parameters        none
  513.  
  514. Reply Parameters
  515.  
  516. keyDirectObject
  517.                   Description:  A list of Apple event
  518.                                 records, one for each
  519.                                 menu, each containing the
  520.                                 following parameters
  521.                   Descriptor Type:  typeAEList
  522.                   Required or Optional?  Required
  523.  
  524.    keyMenuID
  525.                   Description:  The ID of the menu, not
  526.                                 necessarily equal to the
  527.                                 ID of the 'MENU' resource
  528.                                 it may have come from
  529.                   Descriptor Type:  typeShortInteger
  530.                   Required or Optional?  Required
  531.    keyMenuTitle
  532.                   Description:  The title of the menu, as
  533.                                 it appears in the menu bar
  534.                   Descriptor Type:  typeChar
  535.                   Required or Optional?  Required
  536.    keyMenuEnabled
  537.                   Description:  Whether or not the menu, as
  538.                                 a whole, is enabled
  539.                   Descriptor Type:  typeBoolean
  540.                   Required or Optional?  Required
  541.    keyMenuMDEFID
  542.                   Description:  The ID of the menu definition
  543.                                 procedure ('MDEF') resource,
  544.                                 ordinarily 0; -1 signifies
  545.                                 that the definition procedure
  546.                                 is not a resource
  547.                   Descriptor Type:  typeShortInteger
  548.                   Required or Optional?  Required
  549.  
  550. keyMenuEventsTattoo
  551.                   Description:  A null parameter to verify
  552.                                 that Menu Events handled
  553.                                 the event
  554.                   Descriptor Type:  typeNull
  555.                   Required or Optional?  Required
  556.  
  557. Result Codes
  558.                   mBarNFnd        -126    The application has
  559.                                           no menu bar
  560.  
  561.  
  562. Query Menu - list all items in a menu
  563.  
  564. A Query Menu Apple event asks the application to return a list of records
  565. containing information about all items in a given menu (selected by ID
  566. and/or title).  It requests user interaction to bring the application to the
  567. front, then posts mouse events to simulate a click in the menu bar, with
  568. modifier key states as specified, to force the application to update its
  569. menus, then reads the items from the given menu.  This information is
  570. complete enough to reconstruct the menu, except for the icon resources
  571. referenced by the keyMenuItemIcon parameter.
  572.  
  573. Event Class       kMEEventClass
  574.  
  575. Event ID          kAEMEQueryMenu
  576.  
  577. Parameters
  578.  
  579. keyMenuID
  580.                   Description:  The ID of the menu, as
  581.                                 returned by a Query Menu
  582.                                 List Apple event
  583.                   Descriptor Type:  typeShortInteger
  584.                   Required or Optional?  Optional
  585. keyMenuTitle
  586.                   Description:  The title of the menu, as
  587.                                 returned by a Query Menu
  588.                                 List Apple event
  589.                   Descriptor Type:  typeChar
  590.                   Required or Optional?  Optional
  591. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  592. keyShiftKeyPressed
  593.                   Description:  Whether the Shift key is
  594.                                 pressed at the time of the
  595.                                 simulated menu bar click
  596.                   Descriptor Type:  typeBoolean
  597.                   Required or Optional?  Optional
  598.                   Default Value:  false
  599. keyControlKeyPressed
  600.                   Description:  Whether the Control key is
  601.                                 pressed at the time of the
  602.                                 simulated menu bar click
  603.                   Descriptor Type:  typeBoolean
  604.                   Required or Optional?  Optional
  605.                   Default Value:  false
  606. keyOptionKeyPressed
  607.                   Description:  Whether the Option key is
  608.                                 pressed at the time of the
  609.                                 simulated menu bar click
  610.                   Descriptor Type:  typeBoolean
  611.                   Required or Optional?  Optional
  612.                   Default Value:  false
  613. keyCommandKeyPressed
  614.                   Description:  Whether the Command key is
  615.                                 pressed at the time of the
  616.                                 simulated menu bar click
  617.                   Descriptor Type:  typeBoolean
  618.                   Required or Optional?  Optional
  619.                   Default Value:  false
  620.  
  621. Reply Parameters
  622.  
  623. keyDirectObject
  624.                   Description:  A list of Apple event
  625.                                 records, one for each
  626.                                 item, each containing the
  627.                                 following parameters
  628.                   Descriptor Type:  typeAEList
  629.                   Required or Optional?  Required
  630.  
  631.    keyMenuItemID
  632.                   Description:  The ID of the item, numbered
  633.                                 from 1 at the top of the menu
  634.                   Descriptor Type:  typeShortInteger
  635.                   Required or Optional?  Required
  636.    keyMenuItemText
  637.                   Description:  The text of the item, as
  638.                                 it appears in the menu
  639.                   Descriptor Type:  typeChar
  640.                   Required or Optional?  Required
  641.    keyMenuItemEnabled
  642.                   Description:  Whether or not the item is
  643.                                 enabled
  644.                   Descriptor Type:  typeBoolean
  645.                   Required or Optional?  Required
  646.    keyMenuItemMark
  647.                   Description:  The mark character of the
  648.                                 item, in the lower byte
  649.                   Descriptor Type:  typeShortInteger
  650.                   Required or Optional?  Required
  651.    keyMenuItemIcon
  652.                   Description:  The icon number of the item,
  653.                                 which is 256 less than the
  654.                                 resource ID of the 'ICON' or
  655.                                 'cicn' resource
  656.                   Descriptor Type:  typeShortInteger
  657.                   Required or Optional?  Required
  658.    keyMenuItemStyle
  659.                   Description:  The style value of the item,
  660.                                 in the lower byte
  661.                   Descriptor Type:  typeShortInteger
  662.                   Required or Optional?  Required
  663.    keyMenuItemCmd
  664.                   Description:  The Command-key equivalent
  665.                                 character of the item, in the
  666.                                 lower byte
  667.                   Descriptor Type:  typeShortInteger
  668.                   Required or Optional?  Required
  669.  
  670. keyMenuEventsTattoo
  671.                   Description:  A null parameter to verify
  672.                                 that Menu Events handled
  673.                                 the event
  674.                   Descriptor Type:  typeNull
  675.                   Required or Optional?  Required
  676.  
  677. Result Codes
  678.                   mBarNFnd        -126    The application has
  679.                                           no menu bar
  680.                   errAENoUserInteraction
  681.                                   -1713   The application is
  682.                                           refusing to interact
  683.                                           with other processes
  684.                                           or (if Menu Events
  685.                                           extension is locked)
  686.                                           with remote processes
  687.                   noSuchMenuErr   -15950  The application has
  688.                                           no such menu
  689.                   menuMismatchErr
  690.                                   -15955  The given menu ID
  691.                                           and menu title
  692.                                           do not match
  693.  
  694.  
  695. Select Menu Item - perform a menu command
  696.  
  697. A Select Menu Item event simulates the selection of a command (selected
  698. by item ID and/or item text) from a menu (selected by ID and/or title).  It
  699. requests user interaction to bring the application to the front, then posts
  700. mouse events to simulate the selection of the given menu item, with
  701. modifier key states as specified.  If the Menu event is correctly handled,
  702. and the application reacts to the mouse events in the usual way, the result
  703. is as if the user had actually selected that menu item.  Interaction will fail
  704. if the application refuses to interact with other processes
  705. (kAEInteractWithSelf mode), or, if the application is on another machine
  706. and the Menu Events extension has been locked, if it refuses to interact
  707. with remote processes (kAEInteractWithLocal mode).
  708.  
  709. Event Class       kMEEventClass
  710.  
  711. Event ID          kAEMESelectMenuItem
  712.  
  713. Parameters
  714.  
  715. keyMenuID
  716.                   Description:  The ID of the menu, as
  717.                                 returned by a Query Menu
  718.                                 List Apple event
  719.                   Descriptor Type:  typeShortInteger
  720.                   Required or Optional?  Required
  721. keyMenuTitle
  722.                   Description:  The title of the menu, as
  723.                                 returned by a Query Menu
  724.                                 List Apple event
  725.                   Descriptor Type:  typeChar
  726.                   Required or Optional?  Optional
  727. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  728. keyMenuItemID
  729.                   Description:  The ID of the item, numbered
  730.                                 from 1 at the top of the menu
  731.                   Descriptor Type:  typeShortInteger
  732.                   Required or Optional?  Optional
  733. keyMenuItemText
  734.                   Description:  The text of the item, as
  735.                                 it appears in the menu
  736.                   Descriptor Type:  typeChar
  737.                   Required or Optional?  Optional
  738. NOTE:  Either keyMenuItemID or keyMenuItemText, or both, must be
  739. specified.
  740. keyShiftKeyPressed
  741.                   Description:  Whether the Shift key is
  742.                                 pressed at the time of the
  743.                                 simulated menu selection
  744.                   Descriptor Type:  typeBoolean
  745.                   Required or Optional?  Optional
  746.                   Default Value:  false
  747. keyControlKeyPressed
  748.                   Description:  Whether the Control key is
  749.                                 pressed at the time of the
  750.                                 simulated menu selection
  751.                   Descriptor Type:  typeBoolean
  752.                   Required or Optional?  Optional
  753.                   Default Value:  false
  754. keyOptionKeyPressed
  755.                   Description:  Whether the Option key is
  756.                                 pressed at the time of the
  757.                                 simulated menu selection
  758.                   Descriptor Type:  typeBoolean
  759.                   Required or Optional?  Optional
  760.                   Default Value:  false
  761. keyCommandKeyPressed
  762.                   Description:  Whether the Command key is
  763.                                 pressed at the time of the
  764.                                 simulated menu selection
  765.                   Descriptor Type:  typeBoolean
  766.                   Required or Optional?  Optional
  767.                   Default Value:  false
  768.  
  769. Reply Parameters
  770.  
  771. keyMenuEventsTattoo
  772.                   Description:  A null parameter to verify
  773.                                 that Menu Events handled
  774.                                 the event
  775.                   Descriptor Type:  typeNull
  776.                   Required or Optional?  Required
  777.  
  778. Result Codes
  779.                   mBarNFnd        -126    The application has
  780.                                           no menu bar
  781.                   errAENoUserInteraction
  782.                                   -1713   The application is
  783.                                           refusing to interact
  784.                                           with other processes
  785.                                           or (if Menu Events
  786.                                           extension is locked)
  787.                                           with remote processes
  788.                   noSuchMenuErr   -15950  The application has
  789.                                           no such menu
  790.                   noSuchMenuItemErr
  791.                                   -15951  The menu has no
  792.                                           such item
  793.                   menuItemDisabledErr
  794.                                   -15952  The item is
  795.                                           disabled
  796.                   menuEventPendingErr
  797.                                   -15953  Another Menu event
  798.                                           is already pending
  799.                                           on this application
  800.                   menuMismatchErr
  801.                                   -15955  The given menu ID
  802.                                           and menu title
  803.                                           do not match
  804.                   menuItemMismatchErr
  805.                                   -15956  The given menu item ID
  806.                                           and menu item text
  807.                                           do not match
  808.  
  809.  
  810. Constants defined in the Menu Events suite
  811.  
  812. Constant               Value
  813.  
  814. kAEMEQueryMenu         'qmn '
  815. kAEMEQueryMenuList     'qmn#'
  816. kAEMESelectMenuItem    'semi'
  817. keyCommandKeyPressed   'comk'
  818. keyControlKeyPressed   'conk'
  819. keyMenuEnabled         'mnen'
  820. keyMenuEventsTattoo    'Mænu'
  821. keyMenuID              'mnid'
  822. keyMenuItemCmd         'micm'
  823. keyMenuItemEnabled     'mien'
  824. keyMenuItemIcon        'miic'
  825. keyMenuItemID          'miid'
  826. keyMenuItemMark        'mima'
  827. keyMenuItemStyle       'mist'
  828. keyMenuItemText        'mite'
  829. keyMenuMDEFID          'mndf'
  830. keyMenuTitle           'mnti'
  831. keyOptionKeyPressed    'optk'
  832. keyShiftKeyPressed     'shik'
  833. kMEEventClass          'Mænu'
  834. menuEventPendingErr    -15953
  835. menuItemDisabledErr    -15952
  836. menuItemMismatchErr    -15956
  837. menuMismatchErr        -15955
  838. noSuchMenuErr          -15950
  839. noSuchMenuItemErr      -15951
  840.  
  841.  
  842.  
  843. Limitations
  844.  
  845.  
  846. Some applications refuse to submit to the trickery of Menu Events.  The
  847. prime example is any version of Finder which predates the Power
  848. Macintosh (version 7.1.2).  It is not truly an Apple event server, and it
  849. only respects events of known types.  Any other high-level event is not
  850. replied to, and the send will time out.  ResEdit 2.1.1 is similar.  Some
  851. Microsoft applications handle Apple events in a non-standard fashion,
  852. binding their own event handlers over all Apple event classes, and
  853. therefore should not be targeted.
  854.  
  855. The only way to know for sure is to try the ones you are interested in
  856. controlling.  Certainly, anything you write yourself is a candidate, as long
  857. as you follow the practices suggested in Apple documentation, namely:  Be
  858. high-level-event-aware.  Always be ready to accept and dispatch an
  859. Apple event.  Assume that any high-level event you don’t recognize is an
  860. Apple event, and dispatch it as such.  If an unknown event reaches your
  861. wildcard event handler, return errAEEventNotHandled, so that system
  862. event handlers can get a crack at it.  Don’t deny other programs on the
  863. same machine the right to request user interaction, which is the default.
  864.  
  865. Another limitation you should know about is that Menu Events can’t
  866. operate dialogs and alerts which the target application may post in
  867. response to the menu action.  If the menu item text ends in an ellipsis
  868. ('…') character, you can bet that the application will post a dialog or alert
  869. box.  It is then up to the local user to operate the controls.
  870.  
  871. If the target machine is under the influence of a screen saver or security
  872. package which would present a modal dialog in response to a mouse click,
  873. then Query Menu and Select Menu Item events will time out.  The same is
  874. true if the target machine is already showing a modal dialog, preventing
  875. Menu Events from activating the target application.
  876.  
  877. A known conflict exists between Menu Events and Help on Wheels.  If you
  878. send a Menu event to an application which does a casual help display
  879. before performing the menu action, and if the help server is running,
  880. problems may occur with the application.  The problem is that the Menu
  881. event’s user interaction ends when the receiving application sends an
  882. Apple event to the help server, causing it to return to the background.  If
  883. the menu action causes a call to the Standard File Manager or any other
  884. code which should not be called when in the background, the application
  885. may hang.
  886.  
  887.  
  888.  
  889. Programmer Notes
  890.  
  891.  
  892. Write to the author at the above address if you want to know more about
  893. the Menu Events extension or how it was programmed.
  894.  
  895.  
  896.  
  897. Acknowledgements
  898.  
  899.  
  900. Thanks to C.K. Haun and the other folks at Apple Developer Technical
  901. Support who put together those clever little code snippets which give
  902. folks like me such odd ideas.
  903.  
  904. Special thanks to the many fine people who beta-tested this software,
  905. including Ken Linger, Chris Reynolds, Michele Marques, Chris Kaltwasser,
  906. James Edward Davis, and Leonard Rosenthol, and to Fred Terry for his
  907. hospitality at the MacScripting mailing list.
  908.  
  909.  
  910.  
  911. Revision History
  912.  
  913.  
  914. 1.3.1 (December 13, 1997)
  915. •  Public AWOL Utilities 1.4 release.
  916. •  Minor changes to trap patches.
  917.  
  918. 1.3 (March 6, 1996)
  919. •  Public AWOL Utilities 1.3 release.
  920. •  Allowed menus and menu items to be specified using string parameters,
  921. with or without the corresponding numeric ID parameters.  An error is
  922. returned if the numeric and string parameters do not match.
  923. •  Added support for modifier keys (Shift, Control, Option, Command) in
  924. the Query Menu event.
  925. •  Improved application compatibility by simulating a menu bar click, to
  926. force the application to update its menus, before reading the contents of a
  927. menu in response to a Query Menu or Select Menu Item event.
  928. •  Changed the response to a menu selection with the Caps Lock key down
  929. to a simple Apple event recording action, instead of having the target
  930. application send itself a Menu event to invite recording.
  931. •  Added an error string parameter to the reply event when an error
  932. occurs.
  933. •  Moved the error codes from the -21000 range to the -15950 range, so
  934. that errors are reported sensibly in AppleScript alerts.
  935. •  Rewrote “Menu Events Sample Script” to make use of the new optional
  936. string parameters.
  937.  
  938. 1.2 (October 17, 1994)
  939. •  Public AWOL Utilities 1.2 release.
  940. •  No revisions.
  941.  
  942. 1.1.2 (April 19, 1994)
  943. •  Added support for script recording by forcing high-level-event-aware
  944. applications to send themselves Menu events when the user selects a
  945. menu item and the Caps Lock key is down.
  946. •  Added support for modifier keys (Shift, Control, Option, Command) in
  947. the Select Menu Item event.
  948. •  Removed the nonStandardMenuErr (-21004) code in favor of the new
  949. keyMenuMDEFID parameter in the reply to the Query Menu List event, to
  950. improve compatibility with target applications which use slightly
  951. non-standard menu definition procedures.
  952.  
  953. 1.1.1 (April 11, 1994)
  954. •  Added “Menu Events Scripting Addition” and “Menu Events Sample
  955. Script” in place of “Menu Events 'aete'” resource file.
  956.  
  957. 1.1 (March 28, 1994)
  958. •  Public AWOL Utilities 1.1 release.
  959. •  Documented that Menu Events works with Finder 7.1.2.
  960.  
  961. 1.0.7 (March 13, 1994)
  962. •  Menu Events Help presents a useful message if the user tries to open or
  963. print it when the help server is absent.
  964.  
  965. 1.0.6 (February 27, 1994)
  966. •  Added protection against loading duplicate copies of the extension.
  967.  
  968. 1.0.5 (February 6, 1994)
  969. •  Improved compatibility with At Ease and other applications which flush
  970. mouse-down events when they become active.
  971.  
  972. 1.0.4 (January 30, 1994)
  973. •  If the Shift key is pressed on startup, the extension will not be loaded.
  974. If the Help or Command-? key is pressed, the extension will delay up to
  975. one second to let the user release the key(s).
  976.  
  977. 1.0.3 (January 19, 1994)
  978. •  Added “Menu Events 'aete'” resource file.
  979.  
  980. 1.0.2 (January 11, 1994)
  981. •  Fixed bug which sent the target application into a notification wait state
  982. if it received a Menu event from a remote sender.
  983.  
  984. 1.0.1 (December 31, 1993)
  985. •  Initial AWOL Utilities 1.0.1 release.
  986.